//
// Copyright 2001-2004 Stottler Henke Associates, Inc.
// All Rights Reserved.
//////////////////////////////////////////////////////////////////////

package com.stottlerhenke.simbionic.engine.file;

import com.stottlerhenke.simbionic.api.SB_Vector;
import com.stottlerhenke.simbionic.common.SB_FileException;


/**
 * This interface defines methods for reading tokenized data from an
 * abstracted input stream. It hides the low-level details of particular
 * input streams and data formats.  I
 */
public interface SB_StreamReader 
{
	/**
	 * These tag IDs are indices into an array (defined by subclasses)
	 * that actually specifies the tag itself as it appears in the stream.
	 */
  int TAG_FILE_VERSION = 0;
  int TAG_SIM_FORMAT = 1;
  int TAG_PARAMETERS_START = 2;
  int TAG_POLYS_START = 3;
  int TAG_VARIABLES_START = 4;
  int TAG_NODES_START = 5;
  int TAG_BINDINGS_START = 6;
  int TAG_INDICES_START = 7;
  int TAG_TRANSITIONS_START = 8;
  int TAG_CONDITIONS_START = 9;
  int TAG_HIERARCHY_START = 10;
  int TAG_ACTIONS_START = 11;
  int TAG_PREDICATES_START = 12;
  int TAG_GLOBALS_START = 13;
  int TAG_BEHAVIORS_START = 14;
  int TAG_SIM_FILENAME = 15;
  int TAG_CLASSES_START = 16;

	/**
	 * Reads the next integer token from the stream.  Whitespace is consumed.
	 * @return the next integer token from the stream
	 * @throws SB_FileException if the next token is not an integer
	 */
	int readInt() throws SB_FileException;
	
	/**
	 * Reads the next float token from the stream.  Whitespace is consumed.
	 * @return the next float token from the stream
	 * @throws SB_FileException if the next token is not a float
	 */
	float readFloat() throws SB_FileException;
	
	/**
	 * Reads the next boolean token from the stream.  Whitespace is consumed.
	 * @return the next boolean token from the stream
	 * @throws SB_FileException if the next token is not a boolean
	 */
	boolean readBool() throws SB_FileException;

	/**
	 * Reads the next vector from the stream.  Whitespace is consumed.
	 * @return the read vector
	 * @throws SB_FileException if the next sequence is not a vector
	 */
	SB_Vector readVector() throws SB_FileException;
	
	/**
	 * Reads a char from the stream.  If a character is specified,
	 * only that character will be eaten, if it exists.  If mustBePresent
	 * is true, an exception will be thrown if the specified character
	 * is not present.
	 * @param charToRead an optional restriction on the character to read
	 * @param eatWS if true, whitespace will be consumed before reading the char
	 * @param mustBePresent if true and the next character does not match charToRead,
	 *						throws an exception
	 * @throws SB_FileException if the specified character isn't present
	 */
	char readChar(char charToRead,boolean eatWG,boolean mustBePresent)
		throws SB_FileException;
	
	/**
	 * @return a Pascal-style string from the stream
	 * @throws SB_FileException on failure
	 */
	String readPString() throws SB_FileException;
	
	/**
	 * Verifies that the specified section tag is the next item in the 
	 * data stream.
	 * @param tagId the ID of the tag to check
	 * @throws SB_FileException if the specified tag is not present
	 */
	void readSectionTag(int tagId) throws SB_FileException;
}
